Walkthrough

Adds WebGL2 GPU instancing: instance UBO management, instance-aware shader compilation and caching, batching API/signature changes, render-queue instanced draw paths, device/GL helpers, examples and E2E tests, and supporting shader/uniform enhancements.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant RenderQueue as RenderQueue
    participant BatcherManager as BatcherManager
    participant InstanceBatch as InstanceBatch
    participant GPUBuffer as GPU Constant Buffer
    participant ShaderProgram as ShaderProgram

    RenderQueue->>BatcherManager: request instanceBatch (lazy)
    BatcherManager->>InstanceBatch: setLayout(layout)
    InstanceBatch->>GPUBuffer: create/realloc UBO (if needed)
    loop per instanced chunk
        RenderQueue->>InstanceBatch: upload(renderers[], start, count)
        InstanceBatch->>InstanceBatch: pack per-instance fields into CPU buffer
        InstanceBatch->>GPUBuffer: setData(range, Discard)
    end
    RenderQueue->>ShaderProgram: bindUniformBlocks(bindingMap)
    ShaderProgram->>GPUBuffer: uniformBlockBinding(bindingPoint)
    RenderQueue->>RenderQueue: issue drawPrimitive with instanceCount

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 I packed the fields in quiet rows,
UBOs hum where instance data flows,
Shaders peep and vary hue,
Batches leap — five thousand, who knew?
A tiny rabbit hops — render goes!

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Codecov Report

❌ Patch coverage is 40.19015% with 692 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.63%. Comparing base (a54642f) to head (db80ad5).
⚠️ Report is 3 commits behind head on dev/2.0.

@@             Coverage Diff             @@
##           dev/2.0    #2957      +/-   ##
===========================================
- Coverage    77.38%   76.63%   -0.76%     
===========================================
  Files          900      907       +7     
  Lines        98752    99573     +821     
  Branches      9817     9819       +2     
===========================================
- Hits         76415    76303     -112     
- Misses       22170    23097     +927     
- Partials       167      173       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

感谢详细的 review，逐条回复：

Review 1

[P1] ShaderPass.ts:175 — isGPUInstance 未加 WebGL2 守卫

不需要。 上游 _canBatch 已保证 WebGL1 不会启用 gpuInstanceMacro，内部调用链信任上游约束，不做重复防御。只在系统边界（用户输入、外部 API）做防御，内部链路不需要。

[P1] MeshRenderer.ts:177-184 — _canBatch 缺少 renderer 级 shader 状态比较

已修复。 加了 shaderData._macroCollection.isEqual() 检查（commit d58aaa3），系统性覆盖所有 renderer 级宏差异（enableVertexColor、UV flags、用户自定义宏），不需要逐属性枚举。新增了 ShaderMacroCollection.isEqual() 方法，bitmask 数组比较，开销极小。

[P1] ShaderFactory.ts:59-68 — renderer_LocalMat / renderer_MVInvMat derived 但无 #define

已删除这两个 uniform（commit 761bec4）。 引擎内置 shader 没有任何代码使用这两个变量，Unity/Unreal/Godot 也都没有对应的内置变量。删除后还省了每帧一次 Matrix.invert 计算。

[P1] RenderQueue.ts:116 — compileMacros 缺少 renderer 级宏

不存在。 component._globalShaderMacro 在 Renderer._prepareRender 中已经 union 了 camera._globalShaderMacro + renderer.shaderData._macroCollection，renderer 级宏已经包含在内。

[P2] RenderQueue.ts:213-218 — mask 状态未比较

不需要。 SpriteMaskInteraction 是 2D sprite 体系的功能，MeshRenderer 的 _maskInteraction 恒为 None，没有用户 API 可修改。

[P2] ShaderFactory.ts — mat3x4 仿射假设

不需要额外注释。 renderer_ModelMat 是 world matrix，永远是仿射变换（平移+旋转+缩放），第四行恒为 (0,0,0,1)。投影矩阵在 camera 组，不会混到 renderer 的 ModelMat。这是引擎架构保证。

[P2] noise_common.glsl 残留常量

不相关。 本 PR 是 GPU instancing，没有改动 noise 相关文件，与 #2960 不存在文件交叉。

[P2] SubRenderElement.ts dispose — 池复用 NPE

不存在。 dispose() 只在 ObjectPool.garbageCollection() 中调用，调完后 elements.length = 0 清空池子，dispose 过的对象不会被复用，后续 get() 都是 new 新实例。

[P2] GLBuffer.ts — ConstantBuffer 无 WebGL2 检查

不需要。 同 P1 第一条，RHI 层是内部代码，信任上游约束。

[P3] ShaderProgramMap.ts — engine 参数可选

已修复（commit 91e2ce2）。 改为 required。

Review 2

[P0] SubRenderElement.ts:49 — dispose 后池复用 NPE

同上，不存在。 garbageCollection() 后对象被丢弃，不会复用。

[P1] NormalMat inverse() 每顶点计算

确实存在 GPU 开销，但不是本 PR 需要解决的。 非 instancing 路径下 NormalMat 是 CPU 预计算上传的，instancing 路径改为 #define 推导是合理的 tradeoff——避免在 UBO 中多占 64 字节（降低 instanceMaxCount）。对于大多数场景（无 non-uniform scale），可以直接用 mat3(renderer_ModelMat)。这个优化可以作为后续 follow-up。

[P1] 移除 opaque distance sort 影响 overdraw

经过详细分析，不需要恢复距离排序。 移动端 TBDR 架构（Apple HSR、Mali FPK、Adreno LRZ）在硬件层面处理 overdraw，距离排序对 fragment 开销没有收益。顶点开销方面，排不排序都一样（被遮挡物体的顶点仍需处理）。合批优先的排序策略是行业趋势——Unity opaque 队列也是 shader/material 优先，Unreal/Godot 移动端同样不做距离排序。

[P2] InstanceBatch 小批次显存浪费

当前设计合理。 UBO buffer 全局复用（只有一个 InstanceBatch），不是每个 batch 分配一个 buffer。Discard 标记让驱动可以优化小写入。按需分配会引入频繁的 buffer resize，反而更差。

[P2] _scanInstanceUniforms 误匹配注释

概率极低，且 PR 描述已规划 ShaderLab 预编译替代。 不阻塞。

[P2] renderer_MVInvMat derived 无 #define

已删除（同上）。

[P2] _canBatch 中 isWebGL2 每次调用

开销可忽略。 isWebGL2 是一个 boolean 字段读取，不是函数调用。在热路径上这是一次内存读取，远小于后续的 primitive/material 比较开销。

[P3] _derivedDefines 格式

不影响功能，保持现状。

简化建议回复

1. _canBatch 完整等价检查 — 已通过 macroCollection.isEqual() 系统性解决。
2. instancedRenderers 可选字段 — 一个空数组的内存开销可忽略，改可选反而在热路径上增加 null 检查。
3. InstanceBatch.upload modelMatId 分支消除 — 可以做但收益很小（每帧只执行 instanceCount 次），留作后续优化。

Review 5 回复

[P1] NormalMat per-vertex inverse()

同 Review 2 回复。 是已知 trade-off，GPU ALU 换 UBO 空间。大多数场景无 non-uniform scale 时 inverse() 退化为转置，编译器可优化。后续可通过 RENDERER_HAS_NON_UNIFORM_SCALE 宏分两条路径优化。

[P2] _derivedDefines 同时注入 VS 和 FS

需要注入。 renderer_ModelMat（UBO 字段）在 VS 和 FS 中都可能被引用。_derivedDefines 中的三个 define 都依赖 renderer_ModelMat + camera uniforms：

• renderer_MVMat = camera_ViewMat * renderer_ModelMat
• renderer_MVPMat = camera_VPMat * renderer_ModelMat
• renderer_NormalMat = transpose(inverse(mat3(renderer_ModelMat)))

camera uniforms（camera_ViewMat、camera_VPMat）在 VS 和 FS 中都有声明（通过 transform_declare.glsl include），所以 FS 中引用 derived uniform 不会编译失败。用户自定义 shader 如果在 FS 中用 renderer_NormalMat（例如做 bump mapping），不注入会反而出错。

[P2] Opaque 排序移除距离因子

同 Review 2 回复。 移动端 TBDR 硬件处理 overdraw，距离排序无收益。合批优先是行业趋势。

[P2] upload() 中 worldMatrix getter 触发 lazy update

这是 Transform 的公开契约，不是隐式依赖。 transform.worldMatrix getter 保证返回最新值（dirty 时自动更新），这是 Transform 组件的核心设计。引擎内所有需要 worldMatrix 的地方都通过这个 getter 获取。如果未来 Transform 更新策略变化，需要同步修改所有消费者，不限于 instancing 路径。注释已说明。

[P2] _scanInstanceUniforms 正则扫描

同 Review 2 回复。 ShaderLab 预编译路径有结构化元数据，将替代正则方案。

[P3] _builtinRendererUniforms Map

已修复。 最新 commit 已改为 Record<string, boolean>。

Review 6 回复

所有问题在之前的回复中已覆盖，逐条标注：

[P1] NormalMat inverse() — 已回复（Review 2、5）

已知 tradeoff，GPU ALU 换 UBO 空间。后续可优化。

[P1] opaque distance sort — 已回复（Review 2、5）

移动端 TBDR 硬件处理 overdraw，合批优先是行业趋势。

[P2] _derivedDefines 注入 VS 和 FS — 已回复（Review 5）

camera uniforms 在 VS 和 FS 中都有声明（通过 transform_declare.glsl），FS 中引用 derived uniform 不会编译失败。不注入反而会导致用户自定义 shader 在 FS 中使用 renderer_NormalMat 时出错。

[P2] InstanceBatch setData 参数语义 — 误报

GLBuffer.setData 在 Discard 模式下先 gl.bufferData(target, byteLength, usage) orphan 整个 buffer，再 gl.bufferSubData 写入 partial 数据。这是标准的 buffer orphaning 技术，避免 GPU stall。partial write 是正确的。

[P3] _derivedDefines 末行缺 \n — 已回复（Review 2）

不影响功能，保持现状。

Top 1 — SubRenderElement ObjectPool NPE：

Frame 1: new SubRenderElement() → instancedRenderers = [] ← class field
Frame 1: set() → instancedRenderers.length = 0 ← OK
Frame 1: dispose() → instancedRenderers = null ← 置 null
Frame 2: ObjectPool 复用（不走 new，不重新初始化 field）
Frame 2: set() → this.instancedRenderers.length = 0
💥 TypeError: Cannot set property 'length' of null

Fix: dispose() 中 this.instancedRenderers.length = 0 而非 = null。

Top 2 — _buildLayout structSize=0 崩溃：

fieldMap 有 entry 但 type 全不在 _std140TypeInfoMap → addField 全部跳过
→ currentOffset = 0, structSize = 0
→ instanceMaxCount = Math.floor(16384 / 0) = Infinity
→ new ArrayBuffer(Infinity * 0) = new ArrayBuffer(NaN)
💥 RangeError: Invalid array buffer length

Fix:

if (instanceFields.length === 0) return null;
const structSize = Math.ceil(currentOffset / 16) * 16;
const instanceMaxCount = Math.floor(maxUBOSize / structSize);
if (instanceMaxCount < 2) {
  Logger.warn("GPU Instancing: struct too large, falling back");
  return null;
}

感谢详细分析，逐条回复：

Top 1 — SubRenderElement ObjectPool NPE：

不存在。garbageCollection() 在调用 dispose() 后会执行 elements.length = 0 清空整个池子数组，下次 get() 时 elements.length === usedElementCount（都是 0），会走 new SubRenderElement() 创建新实例，不会复用被 dispose 的旧对象。

Top 2 — _buildLayout structSize=0 崩溃：

不存在。_std140TypeInfoMap 覆盖了所有非 sampler 的 GLSL 基础类型（float/int/uint/vec2-4/ivec2-4/mat4/mat3x4），而 _scanInstanceUniforms 已过滤掉 sampler 类型。能进入 fieldMap 的 type 一定在 map 中，不会出现全部跳过的情况。

回复自动 CR（基于 266c346 的 review）：

[P0] structSize=0 导致 Infinity — 不存在。_std140TypeInfoMap 覆盖了所有非 sampler GLSL 基础类型，_scanInstanceUniforms 已过滤 sampler，能进入 fieldMap 的 type 一定在 map 中。

[P1] interface 位置 — 已修复（de638a3）。export 的 InstanceFieldInfo/InstanceLayout 已调整到非 export 的 InstancePackFunc 前面，同时清理了多余的 @internal 和冗余注释。

[P2] array uniform strip 后 undeclared identifier — 已知限制。整体退出 instancing 需要在 RenderQueue 加完整的 fallback 路径（逐 renderer 补 transform upload + uniform upload + draw），改动量大且与 normal draw 逻辑重复。当前方案：官方不支持 renderer shaderData 自定义数组 uniform，Logger.error 提示足够明确。

[P2] isInstanced 与 layout 分层不一致 — 理论隐患但实际不触发。_canBatch 保证同 material + 同 macros，同一 shader 编译结果的所有 pass 要么都有 layout 要么都没有。

简化建议 - _derivedDefines template literal — 可以改，但优先级低。